/*
 * Copyright 2008-2009 Aying.Net Powered by Fuchun.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.aying.media.audio;

import java.io.File;
import java.io.IOException;
import java.net.URL;

/**
 * 定义用于创建 {@link Audio} 音频信息实例的抽象工厂实现。
 * 
 * @author Fuchun
 * @version 1.0, 2009-07-21
 */
public abstract class AudioFactory {

    /**
     * 默认构造方法受到有意保护。
     */
    protected AudioFactory() {}

    /**
     * 创建一个新的 {@code AudioFactory} 音频工厂实例。
     * 
     * @return 新的 {@code AudioFactory} 音频工厂实例。
     */
    public static AudioFactory newInstance() {
        return loadAudioFactory(null);
    }

    /**
     * 创建一个新的指定实现类的完全限定名的 {@code AudioFactory} 音频工厂实例。
     * 
     * @param className {@code AudioFactory} 抽象工厂实现类的完全限定名。
     * @return 指定实现类的新的 {@code AudioFactory} 音频工厂实例。
     */
    public static AudioFactory newInstance(String className) {
        return loadAudioFactory(className);
    }

    @SuppressWarnings("unchecked")
    private static AudioFactory loadAudioFactory(String className) {
        try {
            if (className == null || "".equals(className)) {
                className = "net.aying.media.audio.AudioFactoryImpl";
            }
            Class<AudioFactory> c = (Class<AudioFactory>) Class.forName(className);
            return c.newInstance();
        } catch (Exception ex) {
            throw new RuntimeException(ex);
        }
    }

    /**
     * 根据给定的音频文件的路径创建一个与之相关的 {@link Audio} 实例。
     * 
     * @param audioPath 音频文件路径。
     * @return 与 {@code audioPath} 定位的音频文件相关的 {@link Audio} 实例。
     * @throws IOException 如果读取 {@code audioPath} 音频文件发生 {@code I/O} 错误。
     */
    public abstract Audio createAudio(String audioPath) throws UnsupportedAudioException, IOException;

    /**
     * 根据给定的音频文件创建一个与之相关的 {@link Audio} 实例。
     * <p />
     * 如果指定的音频文件不存在，即 {@code audioFile.exists == false}，则返回 {@code null}。
     * 
     * @param audioFile 音频文件，不能为 {@code null}。
     * @return 与 {@code audioFile} 相关的 {@link Audio} 实例。
     * @throws NullPointerException 如果指定的音频文件为 {@code null}。
     * @throws IOException 如果读取 {@code audioFile} 音频文件发生 {@code I/O} 错误。
     */
    public abstract Audio createAudio(File audioFile) throws UnsupportedAudioException, IOException;

    /**
     * 根据给定的 {@code URL} 定位的音频文件创建一个与之相关的 {@link Audio} 实例。
     * 
     * @param audioURL 定位为音频文件的 {@code URL} 实例。
     * @return 与 {@code audioURL} 相关的 {@link Audio} 实例。
     * @throws IOException 如果读取 {@code audioURL} 定位的音频文件发生 {@code I/O} 错误。
     */
    public abstract Audio createAudio(URL audioURL) throws UnsupportedAudioException, IOException;
}
